---
title: Command Line Interface (CLI)
description: Learn how to use the Motia CLI to manage your projects and workflows
---

# Command Line Interface (CLI)

Motia provides a powerful Command Line Interface (CLI) to help you manage your projects and workflows. The CLI offers various commands for creating projects, generating steps, managing state, and more.

## Installation

The Motia CLI is automatically installed when you install the `motia` package. You can use it by running `npx motia` followed by the desired command.

## Commands

### `create`

Create a new Motia project.

```bash
npx motia@latest create [project-name] [options]
```

**Arguments:**

- `[project-name]` (optional): The name for your project folder. 
  If not provided, you will be prompted to enter it. 
  Use `.` or `./` to create it in the current directory.

**Options:**

- `--template <template-name>` (optional): The template to use for your project. 
  If not provided, you will be prompted to select one interactively.
- `--skip-redis` (optional): Skip the embedded Redis binary installation. 
  Use this when you have your own Redis instance or want to configure external Redis.

**Available Templates:**

Motia provides several project templates to help you get started quickly:

| Template | Description | Use Case |
|----------|-------------|----------|
| `motia-tutorial-typescript` | Tutorial (TypeScript only) | Interactive tutorial project in TypeScript |
| `motia-tutorial-python` | Tutorial (Python only) | Interactive tutorial project in Python |
| `starter-multilang` | Starter (All languages; TS/JS + Python) | Polyglot project with TypeScript API, Python event processing, and JavaScript logging |
| `starter-typescript` | Starter (TypeScript only) | Minimal TypeScript project with basic examples |
| `starter-javascript` | Starter (JavaScript only) | Minimal JavaScript project with basic examples |
| `starter-python` | Starter (Python only) | Minimal Python project with basic examples |

**Examples:**

Create a TypeScript starter project:
```bash
npx motia@latest create my-app --template starter-typescript
```

Create a Python tutorial project:
```bash
npx motia@latest create my-tutorial --template motia-tutorial-python
```

Use interactive mode (no template specified):
```bash
npx motia@latest create
# You'll be prompted to select a template from the list above
```

Create project without embedded Redis (use your own Redis):
```bash
npx motia@latest create my-app --skip-redis
```


### `build`

Build your project, generating zip files for each step and creating a configuration file.

```bash
npx motia build
```

This command:

1. Compiles all your steps (both Node.js and Python)
2. Bundles each step into a zip file
3. Generates a `motia.steps.json` configuration file in the `dist` directory
4. Organizes the output in the `dist` directory

### `deploy`

Deploy your built steps to the Motia deployment service.

```bash
motia cloud deploy --api-key <api-key> --version-name <version> [options]
```

Options:

- `-k, --api-key <key>` (required): Your API key for authentication
- `-n, --project-name <name>`: Project name (used when creating a new project)
- `-s, --environment-id <id>`: Environment ID (can also be set via MOTIA_ENVIRONMENT_ID env var)
- `--environment-name <name>`: Environment name (used when creating a new environment)
- `-v, --version-name <version>` (required): The version to deploy
- `-d, --version-description <description>`: The description of the version
- `-e, --env-file <path>`: Path to environment file

Example:

```bash
motia cloud deploy --api-key your-api-key-here --version-name 1.2.3 --environment-id env-uuid
```

The deployment process:

1. Build your project
2. Uploads each zip file individually with its path information
3. Starts the deployment process on the server

### `dev`

Start the development server with hot reload and Workbench.

```bash
npx motia dev [options]
```

Options:

- `-p, --port <port>`: The port to run the server on (default: 3000).
- `-H, --host [host]`: The host address for the server (default: localhost).
- `-d, --debug`: Enable debug logging.
- `-m, --mermaid`: Enable Mermaid diagram generation.
- `--motia-dir <path>`: Custom path for `.motia` folder.

### `start`

Start the production server without hot reload. Workbench is included by default (can be disabled via `MOTIA_DOCKER_DISABLE_WORKBENCH` environment variable).

```bash
npx motia start [options]
```

Options:

- `-p, --port <port>`: The port to run the server on (default: 3000).
- `-H, --host [host]`: The host address for the server (default: localhost).
- `-d, --debug`: Enable debug logging.
- `--motia-dir <path>`: Custom path for `.motia` folder.

Example:

```bash
# Start production server on port 8080
npx motia start --port 8080

# Start on a specific host
npx motia start --host 0.0.0.0 --port 3000

# Start without Workbench
MOTIA_DOCKER_DISABLE_WORKBENCH=true npx motia start
```

### `get-config`

Get the generated config for your project.

```bash
npx motia get-config [options]
```

Options:

- `-o, --output <path>`: Path to write the generated config file.

### `emit`

Emit an event to the Motia server.

```bash
npx motia emit [options]
```

Options:

- `--topic <topic>` (required): Event topic/type to emit.
- `--message <message>` (required): Event payload as a JSON string.
- `-p, --port <number>`: Port number (default: 3000).

### `generate`

Generate Motia resources.

#### `generate step`

Create a new step with interactive prompts.

```bash
npx motia generate step [options]
```

Options:

- `-d, --dir <step file path>`: The path relative to the steps directory to create the step file.

#### `generate openapi`

Generate OpenAPI spec for your project.

```bash
npx motia generate openapi [options]
```

Options:

- `-t, --title <tile of the document>`: Title for the OpenAPI document. Defaults to project name from package.json.
- `-v, --version <version of the document>`: Version of the OpenAPI document. Defaults to 1.0.0.
- `-o, --output <output file name / path>`: The file name and path relative to root to create the openapi file. Defaults to `openapi.json` at the root.

### `state`

Manage application state.

#### `state list`

List the current file state.

```bash
npx motia state list
```

## Debugging

You can enable debug logging by passing the `-d` or `--debug` flag to the `dev` command:

```bash
npx motia dev --debug
```

This will set the `LOG_LEVEL` environment variable to `'debug'`, providing more detailed logging output.

### `docker`

Tools to help you setup your Motia project with docker and run it inside a container.

#### `docker setup`

Setup your Motia project for Docker

```bash
npx motia docker setup
```

#### `docker build`

Build your Motia project Docker image

```bash
npx motia docker build
```

Options:

- `--project-name <project name>` (required): The name of your project.

#### `docker run`

Run your Motia project inside a container

```bash
npx motia docker run
```

Options:

- `--port <number>`: Port number (default: 3000).
- `--project-name <project name>` (required): The name of your project.
- `--skip-build`: Skip building the Docker image and used the last built image.

## Next Steps

- Explore the [Core Concepts](/docs/concepts) to learn more about Steps, Flows, Events, and Topics.
- Check out the [Examples](/docs/examples) for common patterns and use cases.
- Join our [Community](/community) for help and discussions.
